OpenCode Sub Agent — 子代理委托与并行工作

Sub Agent（子代理）是 OpenCode 的工作委托（Delegation）机制， 允许 Primary Agent 将特定任务分派给专门的子代理独立执行，实现并行工作、关注点分离和权限隔离。 这是 OpenCode Agent 体系区别于传统单线程 AI 编程助手的核心能力之一。

1. 概述

1.1 什么是 Sub Agent

Sub Agent 是一种 mode 为 "subagent" 的 Agent 实例， 不能由用户直接交互（不可通过 Tab 切换）， 而是由 Primary Agent 在 ReAct 循环中通过 task 工具调度执行， 或由用户通过 @agent-name 手动调用。

1.2 Primary Agent vs Sub Agent

2. 行为分析（做什么）

以下从行为视角分析 Sub Agent 的功能边界与委托执行流程。

2.1 用例图 — Sub Agent 的使用场景全景

展示 Sub Agent 的两类调用者（Primary Agent / 用户）与其可委托的任务类型。

图 1：Sub Agent 顶层用例图

2.2 活动图 — Sub Agent 委托执行流程

展示从 Primary Agent 决策委托到 Sub Agent 完成返回的完整活动链，覆盖权限门控和深度检查。

图 2：Sub Agent 委托执行活动图（带泳道）

2.3 序列图 — Task Tool 调度 Sub Agent 完整序列

以 Build Agent 委托 Explore Agent 搜索 API 端点为例，展示从 task 工具调用到子会话创建、独立 ReAct 循环执行、结果序列化返回的全链路消息流。

图 3：Task Tool → Sub Agent 完整调用序列图（Explore Agent 示例）

序列图关键节点解读

3. 结构分析（由什么组成）

3.1 组件图 — Sub Agent 调度架构

展示 Sub Agent 调度系统的分层组件架构：Primary Agent → Task Tool Dispatcher（权限门控 + 深度门控）→ Sub Agent Registry → Sub Agent Runtime（Session Manager + ReAct Loop + System Prompt Loader）→ 过滤后的工具层。

图 4：Sub Agent 调度系统组件架构图

4. 内置 Sub Agent 详解

OpenCode 提供 3 个内置 Sub Agent，源码位于 packages/core/src/plugin/agent.ts 和 packages/opencode/src/agent/prompt/*.txt。

4.1 General

4.2 Explore

4.3 Scout

5. Task Tool — Sub Agent 的调度入口

task 工具是 Primary Agent 与 Sub Agent 之间的唯一接口。 Primary Agent 的 LLM 产出 tool_call: task(...)，由 Runtime 层解析、 创建子会话、注入 Sub Agent Prompt、启动独立 ReAct 循环、最终将结果序列化返回。

5.1 参数 Schema

5.2 调度流程

6. 自定义 Sub Agent

6.1 JSON 配置方式

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.1,
      "steps": 10,
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

6.2 Markdown 配置方式

放在 ~/.config/opencode/agents/（全局）或 .opencode/agents/（项目级）：

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
steps: 8
---
You are a technical writer. Create clear, comprehensive documentation.
Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

6.3 配置选项全览

7. Sub Agent System Prompt

Sub Agent 启动时用自己的专属 System Prompt替换 Primary Agent 的模型专属 Prompt。位于 packages/opencode/src/agent/prompt/*.txt。

8. 实战速查手册

8.1 配置键速查

8.2 调用流程速查

8.3 权限速查

9. 源码分析 — 关键实现路径

以下基于 packages/opencode/src/tool/task.ts 和 task.txt 源码，厘清 Sub Agent 的创建、调度与并发模型。

9.1 Child Session 创建

Sub Agent 的底层实体是 child Session，而非操作系统线程。 调用 task 工具时，task.ts:142-158 走 sessions.create({ parentID, ... }) 创建一条子会话记录， 随后通过 BackgroundJob.start()（task.ts:259）将任务以 Effect Fiber（协程）形式调度执行。

9.2 并发与重入

task.txt:13 明确指示：

结合源码得到以下结论：

9.3 组件总表